chore(openspec): migrate specs to v4 structure and enforce validation - #258
Open
cleithner-comcast wants to merge 2 commits into
Open
chore(openspec): migrate specs to v4 structure and enforce validation#258cleithner-comcast wants to merge 2 commits into
cleithner-comcast wants to merge 2 commits into
Conversation
All 35 specs under openspec/specs/ were authored in the older delta format and failed `openspec validate --specs --strict`. Flatten them to the v4 main-spec structure (title + Purpose + Requirements) with no change to requirement meaning, and enforce that structure going forward: - install a pinned openspec CLI in the builder image (version bump 2.14 -> 2.17) - add .github/workflows/validate-openspec.yaml running strict validation - add a pre-commit hook running the same strict validation - vendor the gh-stack agent skill (gh skill install is unavailable here) Adds the migrate-specs-to-v4 OpenSpec change (proposal, design, specs, tasks). All 35 specs now pass strict validation.
cleithner-comcast
requested review from
kfundecmcsa,
mkkoch,
rchowdcmcsa and
tleacmcsa
as code owners
August 4, 2026 15:22
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Comment on lines
+39
to
+43
| name: Get Action Constants | ||
| uses: ./.github/workflows/action-constants.yaml | ||
| secrets: inherit | ||
|
|
||
| validate_openspec_specs: |
Comment on lines
+44
to
+74
| name: Validate OpenSpec Specs | ||
| runs-on: ubuntu-latest | ||
| needs: get-action-constants | ||
|
|
||
| steps: | ||
| - | ||
| name: Checkout code | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: ${{ github.repository }} | ||
| fetch-depth: 0 | ||
| fetch-tags: true | ||
| - | ||
| name: Log in to GitHub Container Registry | ||
| uses: docker/login-action@v2 | ||
| with: | ||
| registry: ghcr.io | ||
| username: ${{ github.actor }} | ||
| password: ${{ secrets.GITHUB_TOKEN }} | ||
| - | ||
| name: Try to pull barton_builder Docker image | ||
| continue-on-error: true | ||
| run: | | ||
| if docker pull ${{ needs.get-action-constants.outputs.image_repo }}:${{ needs.get-action-constants.outputs.image_tag }}; then | ||
| echo "Image pulled successfully" | ||
| else | ||
| echo "Could not pull image, will build locally via dockerw" | ||
| fi | ||
| - | ||
| name: Validate specs (strict) | ||
| run: ./dockerw -n openspec validate --specs --strict --no-interactive |
| fetch-tags: true | ||
| - | ||
| name: Log in to GitHub Container Registry | ||
| uses: docker/login-action@v2 |
Contributor
There was a problem hiding this comment.
Pull request overview
Migrates the repository’s OpenSpec main specs to the v4 “main-spec” structure (Title + Purpose + Requirements) and adds enforcement so openspec validate --specs --strict becomes a consistently green, CI-gated invariant going forward. It also introduces a documented OpenSpec change (“migrate-specs-to-v4”) capturing the rationale/design/tasks for the migration and enforcement.
Changes:
- Flatten all
openspec/specs/**/spec.mddocuments from delta headers into v4 main-spec structure (and add per-spec Purpose sections). - Provision and enforce strict spec validation via a pinned
openspecCLI in the builder image, a new GitHub Actions workflow, and a pre-commit hook. - Vendor the
gh-stackagent skill into.github/skills/gh-stack/and add the OpenSpec change artifacts for traceability.
Reviewed changes
Copilot reviewed 48 out of 48 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| openspec/specs/zigbee-subsystem/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/vendor-product-claiming/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/thread-subsystem/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/temperature-humidity-sbmd-drivers/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/sbmd-v4-runtime/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/sbmd-v4-light-driver/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/sbmd-system/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/sbmd-seed-from-attribute/spec.md | Add v4 title/purpose/requirements header for the spec. |
| openspec/specs/sbmd-script-execution-limits/spec.md | Flatten delta sections into v4 requirements section; remove leftover delta header. |
| openspec/specs/sbmd-runtime-observability/spec.md | Reword one requirement to be normative (SHALL) for strict validation. |
| openspec/specs/sbmd-resource-prerequisites/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/resource-model/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/release-workflow/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/python-sideband-client/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/public-api/spec.md | Convert to v4 structure; add scenarios needed for strict validation. |
| openspec/specs/observability-metrics/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/matterjs-virtual-device-framework/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/matterjs-door-lock-device/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/matter-thermostat-testing/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/matter-thermostat-sbmd/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/matter-test-infrastructure/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/matter-subsystem/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/endpoint-cluster-fallback/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/device-type-endpoint-resolution/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/device-drivers/spec.md | Convert to v4 structure; reword non-normative language and add scenarios. |
| openspec/specs/core-services/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/changelog-generation/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/build-system/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-validate-sbmd/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-unit-tests/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-matter-devices/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-integration-tests/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-format-code/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-debug/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/specs/agent-skill-build/spec.md | Convert to v4 main-spec structure (title/purpose/requirements). |
| openspec/changes/migrate-specs-to-v4/tasks.md | Add implementation task list for the migration/enforcement change. |
| openspec/changes/migrate-specs-to-v4/specs/spec-validation/spec.md | Add delta spec capturing new validation/enforcement requirements. |
| openspec/changes/migrate-specs-to-v4/proposal.md | Add change proposal documenting motivation/scope/impact. |
| openspec/changes/migrate-specs-to-v4/design.md | Add design decisions/risks/migration plan for the change. |
| openspec/changes/migrate-specs-to-v4/.openspec.yaml | Declare change schema and creation date. |
| hooks/pre-commit | Add local strict OpenSpec validation to pre-commit. |
| docker/version | Bump builder image version to reflect new tooling. |
| docker/Dockerfile | Install pinned openspec CLI (via npm) into the builder image. |
| .github/workflows/validate-openspec.yaml | Add CI gate that runs strict OpenSpec validation in PRs. |
| .github/skills/gh-stack/SKILL.md | Vendor gh-stack agent skill documentation. |
| .github/skills/gh-stack/references/troubleshooting.md | Vendor gh-stack troubleshooting reference. |
| .github/skills/gh-stack/references/stack-design.md | Vendor gh-stack stack design reference. |
| .github/skills/gh-stack/references/commands.md | Vendor gh-stack command behavior reference. |
Comment on lines
+38
to
+45
| # OpenSpec: enforce that every spec conforms to the v4 structure. The dev | ||
| # container provides the pinned openspec CLI; when it is absent (commits made | ||
| # outside the container), skip and rely on the CI gate. | ||
| if command -v openspec >/dev/null 2>&1; then | ||
| openspec validate --specs --strict --no-interactive | ||
| else | ||
| echo "pre-commit: openspec not found on PATH; skipping spec validation (CI will enforce)." >&2 | ||
| fi |
Comment on lines
+1
to
+5
| --- | ||
| name: gh-stack | ||
| description: > | ||
| Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack. | ||
| Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout; |
…csV4 # Conflicts: # docker/version
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 48 out of 48 changed files in this pull request and generated no new comments.
Suppressed comments (4)
openspec/changes/migrate-specs-to-v4/proposal.md:26
- This states the builder image version bump is
2.14 → 2.17, but the actualdocker/versionchange in this PR is2.15 → 2.17. Update the proposal to match the repository’s current prior version so the change record stays accurate.
- **Build image**: `docker/Dockerfile` gains a pinned `openspec` install (Node.js 22 is already present); `docker/version` bumped (2.14 → 2.17, chosen to avoid collision with in-flight builder bumps on parallel branches). Consumers must repull the builder image.
openspec/changes/migrate-specs-to-v4/design.md:24
- The design doc claims
docker/versionis currently2.14and references a2.14 → 2.17bump, but the repo’s prior version is2.15(per thedocker/versiondiff). Please update these numbers to keep the design document consistent with the actual history.
Node.js 22 is already installed in the builder image, so the `openspec` npm CLI can be added there. `docker/version` is currently `2.14`.
openspec/changes/migrate-specs-to-v4/design.md:54
- The design doc claims
docker/versionis currently2.14and references a2.14 → 2.17bump, but the repo’s prior version is2.15(per thedocker/versiondiff). Please update these numbers to keep the design document consistent with the actual history.
docker/version: 2.14 → 2.17 (2.15/2.16 taken by parallel branches)
openspec/changes/migrate-specs-to-v4/tasks.md:17
- This task item indicates
docker/versionwas bumped2.14 → 2.17, but the actual change shown indocker/versionis2.15 → 2.17. Update the task text to reflect the real before/after versions so the checklist remains an accurate audit trail.
- [x] 3.2 Bump `docker/version` (2.14 → 2.17)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
All 35 specs under openspec/specs/ were authored in the older delta format and failed
openspec validate --specs --strict. Flatten them to the v4 main-spec structure (title + Purpose + Requirements) with no change to requirement meaning, and enforce that structure going forward:Adds the migrate-specs-to-v4 OpenSpec change (proposal, design, specs, tasks). All 35 specs now pass strict validation.
Stack created with GitHub Stacks CLI • Give Feedback 💬